About {gs}

gs is a grammar of recurring calendar events, implemented as an R package. It enables users to easily create and work with schedules, even in cases when the pattern of events is irregular.

gs does this by providing a set of simple to understand functions for making schedules along with functions for combining them to form more complex ones.

The gs grammar is both flexible and declarative. The flexibility allows users to compose arbitrarily complex schedules from simple and intuitive buildings blocks. Because the grammar is declarative, the user need not concern themselves with the details of how a particular schedule works, rather they can specify what they want from a schedule and let gs implement it for them.

About me

My name is James Laird-Smith and I am a data analyst at the Financial Times in London.

Simple examples

Weekly until fixed date

library(gs)
library(lubridate)
library(magrittr)

on_every("week", starting = ymd("1997-09-02")) %>% 
  only_occur(before(ymd("1997-12-24"))) %>% 
  schedule_days(during = 1997)

 [1] "1997-09-02"
 [2] "1997-09-09"
 [3] "1997-09-16"
 [4] "1997-09-23"
 [5] "1997-09-30"
 [6] "1997-10-07"
 [7] "1997-10-14"
 [8] "1997-10-21"
 [9] "1997-10-28"
[10] "1997-11-04"
[11] "1997-11-11"
[12] "1997-11-18"
[13] "1997-11-25"
[14] "1997-12-02"
[15] "1997-12-09"
[16] "1997-12-16"
[17] "1997-12-23"

Weekly until December 24, 1997

Every other week

on_every_second("week", starting = ymd("1997-09-02")) %>% 
  schedule_days(from = 1997, to = 1998)

 [1] "1997-09-02"
 [2] "1997-09-16"
 [3] "1997-09-30"
 [4] "1997-10-14"
 [5] "1997-10-28"
 [6] "1997-11-11"
 [7] "1997-11-25"
 [8] "1997-12-09"
 [9] "1997-12-23"
[10] "1998-01-06"
[11] "1998-01-20"
[12] "1998-02-03"
[13] "1998-02-17"
[14] "1998-03-03"
[15] "1998-03-17"
[16] "1998-03-31"
[17] "1998-04-14"
[18] "1998-04-28"
[19] "1998-05-12"
[20] "1998-05-26"
[21] "1998-06-09"
[22] "1998-06-23"
[23] "1998-07-07"
[24] "1998-07-21"
[25] "1998-08-04"
[26] "1998-08-18"
[27] "1998-09-01"
[28] "1998-09-15"
[29] "1998-09-29"
[30] "1998-10-13"
[31] "1998-10-27"
[32] "1998-11-10"
[33] "1998-11-24"
[34] "1998-12-08"
[35] "1998-12-22"

Every other week - forever:

Advanced examples

Weekly on Tuesday and Thursday for five weeks:

on_wday("Tue", "Thu") %>% 
  only_occur(on_or_after(ymd("1997-09-02"))) %>% 
  schedule_days(to = ymd("1997-09-02") + weeks(5))

 [1] "1997-09-02"
 [2] "1997-09-04"
 [3] "1997-09-09"
 [4] "1997-09-11"
 [5] "1997-09-16"
 [6] "1997-09-18"
 [7] "1997-09-23"
 [8] "1997-09-25"
 [9] "1997-09-30"
[10] "1997-10-02"
[11] "1997-10-07"

Every other week on Monday, Wednesday, and Friday

in_every_second("week", starting = ymd("1997-09-01")) %>% 
  only_occur(on_or_before(ymd("1997-12-24"))) %>% 
  schedule_days(during = 1997)

 [1] "1997-09-01"
 [2] "1997-09-02"
 [3] "1997-09-10"
 [4] "1997-09-11"
 [5] "1997-09-12"
 [6] "1997-09-13"
 [7] "1997-09-14"
 [8] "1997-09-15"
 [9] "1997-09-16"
[10] "1997-09-24"
[11] "1997-09-25"
[12] "1997-09-26"
[13] "1997-09-27"
[14] "1997-09-28"
[15] "1997-09-29"
[16] "1997-09-30"
[17] "1997-10-08"
[18] "1997-10-09"
[19] "1997-10-10"
[20] "1997-10-11"
[21] "1997-10-12"
[22] "1997-10-13"
[23] "1997-10-14"
[24] "1997-10-22"
[25] "1997-10-23"
[26] "1997-10-24"
[27] "1997-10-25"
[28] "1997-10-26"
[29] "1997-10-27"
[30] "1997-10-28"
[31] "1997-11-05"
[32] "1997-11-06"
[33] "1997-11-07"
[34] "1997-11-08"
[35] "1997-11-09"
[36] "1997-11-10"
[37] "1997-11-11"
[38] "1997-11-19"
[39] "1997-11-20"
[40] "1997-11-21"
[41] "1997-11-22"
[42] "1997-11-23"
[43] "1997-11-24"
[44] "1997-11-25"
[45] "1997-12-03"
[46] "1997-12-04"
[47] "1997-12-05"
[48] "1997-12-06"
[49] "1997-12-07"
[50] "1997-12-08"
[51] "1997-12-09"
[52] "1997-12-17"
[53] "1997-12-18"
[54] "1997-12-19"
[55] "1997-12-20"
[56] "1997-12-21"
[57] "1997-12-22"
[58] "1997-12-23"

Holidays

U.S. Independence Day

on_us_independence_day <- 
  only_occur(on_mday(4), 
             in_month("July"))

on_us_independence_day %>% 
  schedule_days(from = 2020, to = 2025)

[1] "2020-07-04"
[2] "2021-07-04"
[3] "2022-07-04"
[4] "2023-07-04"
[5] "2024-07-04"
[6] "2025-07-04"

In the United States Independence Day is celebrated on.

Martin Luther King Jr. Day

on_mondays <- on_wday("Mon")
in_jan <- in_month("Jan")

on_mlk_day <- 
  on_third(on_mondays, 
           within_given = "month") %>% 
  only_occur(in_jan) 

on_mlk_day %>% 
  schedule_days(from = 2020, to = 2025)

[1] "2020-01-20"
[2] "2021-01-18"
[3] "2022-01-17"
[4] "2023-01-16"
[5] "2024-01-15"
[6] "2025-01-20"

Martin Luther King Jr. Day is a national holiday United States occuring every year on the third Monday in January.

This means Martin Luther King Day is a apparently complicated schedule. But, if using gs, even apparently complicated schedules can easily be created from simple building blocks.

In the first section of code, we create the component schedules.

Combine holidays

# on_us_independence_day <- 
#   only_occur(on_mday(4), 
#              in_month("July"))
# on_mlk_day <- 
#   on_third(on_wday("Mon"), 
#            within_given = "month") %>% 
#   only_occur(in_month("Jan"))

on_us_federal_holidays <-
  on_us_independence_day %>% 
  also_occur(on_mlk_day)

on_us_federal_holidays %>% 
  schedule_days(from = 2020, to = 2022)

[1] "2020-01-20"
[2] "2020-07-04"
[3] "2021-01-18"
[4] "2021-07-04"
[5] "2022-01-17"
[6] "2022-07-04"

Here is some commentary